home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / ewl / Ewl.h < prev   
Encoding:
C/C++ Source or Header  |  2006-01-09  |  11.7 KB  |  339 lines
  1. #ifndef _EWL_H
  2. #define _EWL_H
  3.  
  4. /**
  5.  * @file Ewl.h
  6.  * @brief The file that should be included by any project using EWL.
  7.  * It provides all the necessary headers and includes to work with EWL,
  8.  * it is discouraged to include each header file individually.
  9.  */
  10.  
  11. /**
  12.  * @mainpage Enlightened Widget Library Documentation
  13.  *
  14.  * @section intro Introduction
  15.  *
  16.  * The Enlightened Widget Library (EWL) is a widget toolkit based on the
  17.  * libraries provided for Enlightenment 17 development. Rendering is performed
  18.  * using Evas, a fast abstracted canvas library that supports multiple
  19.  * backends. The appearances of the widgets are described by Edje files,
  20.  * which are essentially files containing a collection of images and
  21.  * descriptions for laying out those images. The goal of EWL is to abstract
  22.  * the use of these backends and to present an easy to use object model to the
  23.  * end programmer.
  24.  *
  25.  * Overall, EWL is similar in design and functionality to other common
  26.  * toolkits such as GTK+ and QT. The API's differ, but the overall concepts
  27.  * and ideas are similar. If you are familiar with these other toolkits,
  28.  * getting into EWL should be relatively simple.
  29.  *
  30.  * EWL uses the concept of inheritance for describing it's widgets. When a
  31.  * class inherits from another class, the functions that operated on the base
  32.  * class can also operate on the inheriting class. For example, in EWL the
  33.  * class Ewl_Button inherits from Ewl_Box, which inherits from Ewl_Container.
  34.  * This means you can add widgets to the button, just like you could to the
  35.  * box or any other container by using ewl_container_append. Since EWL is
  36.  * written in C, it uses a very simple single inheritance system. The first
  37.  * field of the inheriting struct must be the inherited struct, and note, it's
  38.  * not a pointer to the inherited struct. For example:
  39.  *
  40.  * @code
  41.  * struct Ewl_Foo
  42.  * {
  43.  *     Ewl_Bar bar;
  44.  *     int baz;
  45.  * };
  46.  * @endcode
  47.  *
  48.  * Creates a new class of objects, Foo, which inherits from the Bar class and
  49.  * extends it by adding an integer baz. If the first line of the struct had
  50.  * been Ewl_Bar *bar; it would most likely result in some buffer overflows
  51.  * when initializing the widget.
  52.  *
  53.  * @section model The Object Model
  54.  *
  55.  * The basis for all widgets in EWL is the Ewl_Object. Ewl_Objects are never
  56.  * allocated outside of another widget, it provides size and position
  57.  * information for the widget as well as info about it's padding and insets.
  58.  * There are also fields for indicating object alignment and fill policies.
  59.  * Eventually, it will also contain a type field, which will essentially be a
  60.  * colon separated listing of all the inheriting classes for a particular
  61.  * widget.
  62.  *
  63.  * The next step above the Ewl_Object is the Ewl_Widget. Again, these are
  64.  * never allocated by themselves, but are part of all the other widgets
  65.  * available in EWL. The Ewl_Widget class provides necessary information about
  66.  * a widget that relates to it's appearance, it's parent container, event
  67.  * handling, as well as a few miscellaneous tasks common to all widgets.
  68.  *
  69.  * A necessary class that some widgets inherit from is Ewl_Container. This is
  70.  * used for holding collections of widgets and laying them out. Containers are
  71.  * the building blocks of the widget set, they allow for creating heirarchies
  72.  * of widgets that are bounded within their parent containers. The class
  73.  * inherits from Ewl_Widget, so that any container can also be treated as a
  74.  * widget, and thus you can put containers within other containers. Examples
  75.  * of inheriting classes are Ewl_Window and Ewl_Box. In the case of the
  76.  * Ewl_Window, widgets inside the window are given any position they request
  77.  * within the insets of the window. For the Ewl_Box, contained widgets are
  78.  * layed out either from top to bottom, or from left to right, depending on
  79.  * the box orientation.
  80.  *
  81.  * @section callbacks Callbacks
  82.  *
  83.  * To do work in a GUI, it is necessary to know when certain actions occur.
  84.  * EWL handles notification of actions using a common technique called
  85.  * callbacks. When the end programmer wants to know when a specific event
  86.  * occurs to a widget, they can add a callback to it using ewl_callback_append
  87.  * or one of the similar functions. One of the arguments to these functions is
  88.  * a pointer to a function. This function will get called when EWL receives
  89.  * the specified event on that widget. You can attach callbacks to any widget,
  90.  * and with containers you can even mark them to intercept events to their
  91.  * child widgets.
  92.  *
  93.  * One feature of EWL that is different from other toolkits is that it makes
  94.  * extensive use of internal callbacks. In fact, almost all appearance changes
  95.  * for widgets are actually callbacks, and most of the ewl_widget calls
  96.  * actually do very little work, but trigger specific callbacks. This feature
  97.  * allows for overriding specific actions on a widget, or for ordering user
  98.  * specified callbacks relative to internal ones.
  99.  * Example Application Walk-through
  100.  *
  101.  * One of the easiest applications to build for EWL is a simple image viewer.
  102.  * The basic image viewer needs a window, and an image widget. The following
  103.  * app is a fully functional simple image viewer based on code written by Ben
  104.  * Rockwood of Cuddletech. The first part necessary for creating an EWL
  105.  * application is to include the necessary header Ewl.h. Following the include
  106.  * statements are global variable declarations.
  107.  *
  108.  * @code
  109.  * #include <Ewl.h>
  110.  *
  111.  * Ewl_Widget *main_win;
  112.  * Ewl_Widget *main_box;
  113.  * Ewl_Widget *image;
  114.  * @endcode
  115.  *
  116.  * Now declarations of function callbacks are
  117.  * made, normally when writing an application
  118.  * these are added after the GUI code is written.
  119.  * The next piece of code is common to most apps,
  120.  * the windows in EWL are not closed unless they
  121.  * are destroyed, so a callback must be attached
  122.  * for the windows delete callback.
  123.  *
  124.  * @code
  125.  * void
  126.  * __destroy_main_window(Ewl_Widget *main_win, void *ev_data, void *user_data)
  127.  * {
  128.  *     ewl_widget_destroy(main_win);
  129.  *     ewl_main_quit();
  130.  *
  131.  *     return;
  132.  * }
  133.  * @endcode
  134.  *
  135.  * For this simple application, that is the only necessary callback, now we
  136.  * have the main function.  This is where EWL is initialized,
  137.  * widgets are created, and the main EWL loop is started.  First,
  138.  * declare the main function and check to be sure that an image
  139.  * file was specified, then initialize the EWL library.
  140.  *
  141.  * @code
  142.  * int main (int argc, char **argv)
  143.  * {
  144.  *     if (argc < 2) {
  145.  *        fprintf(stderr, "Usage: %s <image>\n", argv[0]);
  146.  *        return 1;
  147.  *     }
  148.  *    ewl_init(&argc, argv);
  149.  * @endcode
  150.  *
  151.  * Next allocate the window, set it's title and attach a callback to catch it's
  152.  * delete event.  Also, set a minimum size on the window, also mark it to be
  153.  * auto-sized, and visible.  Marking it auto-sized will cause the widget to
  154.  * resize to fit the contents.
  155.  *
  156.  * @code
  157.  *     main_win = ewl_window_new();
  158.  *     ewl_window_title_set(EWL_WINDOW(main_win), "EWL Simple Image Viewer");
  159.  *     ewl_callback_append(main_win, EWL_CALLBACK_DELETE_WINDOW,
  160.  *                __destroy_main_window, NULL);
  161.  *     ewl_object_minimum_size_set(EWL_OBJECT(main_win), 100, 100);
  162.  *     ewl_widget_show(main_win);
  163.  * @endcode
  164.  *
  165.  * Now we create a box for holding the image, this is not really necessary for
  166.  * this app, but it demonstrates further how to use containers, and makes it
  167.  * easier to add more widgets later.
  168.  *
  169.  * @code
  170.  *     main_box = ewl_vbox_new();
  171.  *     ewl_container_child_append(EWL_CONTAINER(main_win), main_box);
  172.  *     ewl_widget_show(main_box);
  173.  * @endcode
  174.  *
  175.  * Next, create the image widget, we just attempt to load the image
  176.  * file that was specified on the command line, and add it to the
  177.  * box in the window. The second argument is NULL for normal images, but can
  178.  * be set to the name of the group to load for an edje.
  179.  *
  180.  * @code
  181.  *     image = ewl_image_new();
  182.  *    ewl_image_file_set(EWL_IMAGE(image), argv[1], NULL);
  183.  *     ewl_container_child_append(EWL_CONTAINER(main_box), image);
  184.  *     ewl_widget_show(image);
  185.  * @endcode
  186.  *
  187.  * Finally, we call the main function that starts the EWL event
  188.  * processing loop, and with that our app is complete.
  189.  *
  190.  * @code
  191.  *     ewl_main();
  192.  *
  193.  *     return 0;
  194.  * }
  195.  * @endcode
  196.  *
  197.  * Now that the application source has been written, it must be
  198.  * compiled. This is fairly simple with EWL, if you name the app
  199.  * simple_viewer.c just use the command:
  200.  *
  201.  * gcc -o simple_viewer `ewl-config --cflags --libs` simple_viewer.c
  202.  *
  203.  * @section conclusion Conclusion
  204.  *
  205.  * Obviously, creating a simple image viewer does not take much
  206.  * effort at all, but it is a good basis for understanding the
  207.  * basics of EWL.  Hopefully, readers will extend this app, and
  208.  * possibly create more robust image viewers, and with any luck,
  209.  * other applications to demonstrate EWL's capabilities.
  210.  *
  211.  * If you have questions, corrections, or improvements, please send
  212.  * them to <a href="mailto: rbdpngn@users.sourceforge.net">RbdPngn</a>. 
  213.  */
  214.  
  215. /**
  216.  * @page layering Layering Scheme
  217.  *
  218.  * As widgets are placed inside containers, there becomes the issue of
  219.  * specifying which gets drawn on top. It is important that the widgets placed
  220.  * inside of a container are above the container's background, or the user
  221.  * would be unable to view the placed widgets.
  222.  *
  223.  * The current scheme to accomplish this is that each widget has a layer
  224.  * field. This field is an integer that indicates an offset relative to it's
  225.  * parent containers layer. The default value is 5, which raises any widgets
  226.  * inside of a container 5 layers above the container. This use of offsets
  227.  * allows for children that have the same level of nesting to be at the same
  228.  * layer in the Evas.
  229.  *
  230.  * Unfortunately, this also means that if two containers overlap, the children
  231.  * may seem to intermingle as they are above the layers of their containers.
  232.  * So far this has not become an issue, but it may in the future. See the
  233.  * diagram below for further information.
  234.  *
  235.  * @image html layer-problem.png
  236.  *
  237.  * One issue that did occur was with the imenu's popup portion. It was placed
  238.  * at the first level above the window, so the contents of the menu were
  239.  * overlapped by items placed in nested containers in the window.
  240.  */
  241.  
  242. /**
  243.  * @page images Documentation Images
  244.  *
  245.  * Diagram describing Ewl_Object fields
  246.  *
  247.  * @image html object_fields.png
  248.  *
  249.  * Diagram describing how Ewl_Object fields affect sizing
  250.  *
  251.  * @image html object_sizing.png
  252.  */
  253.  
  254. #ifdef __cplusplus
  255. extern"C" {
  256. #endif
  257.  
  258. #include <Evas.h>
  259. #include <Ecore.h>
  260. #include <Ecore_Data.h>
  261.  
  262. #include <ewl_enums.h>
  263.  
  264. #include <ewl_object.h>
  265. #include <ewl_widget.h>
  266.  
  267. #include <ewl_attach.h>
  268.  
  269. #include <ewl_container.h>
  270.  
  271. #include <ewl_callback.h>
  272. #include <ewl_events.h>
  273.  
  274. #include <ewl_misc.h>
  275.  
  276. #include <ewl_box.h>
  277. #include <ewl_freebox.h>
  278. #include <ewl_border.h>
  279.  
  280. #include <ewl_cell.h>
  281. #include <ewl_row.h>
  282.  
  283. #include <ewl_grid.h>
  284. #include <ewl_table.h>
  285.  
  286. #include <ewl_config.h>
  287. #include <ewl_theme.h>
  288.  
  289. #include <ewl_label.h>
  290. #include <ewl_button.h>
  291. #include <ewl_floater.h>
  292. #include <ewl_overlay.h>
  293. #include <ewl_embed.h>
  294. #include <ewl_window.h>
  295. #include <ewl_dialog.h>
  296. #include <ewl_fileselector.h>
  297. #include <ewl_filedialog.h>
  298.  
  299. #include <ewl_text.h>
  300. #include <ewl_entry.h>
  301.  
  302. #include <ewl_colorpicker.h>
  303. #include <ewl_colordialog.h>
  304. #include <ewl_password.h>
  305. #include <ewl_seeker.h>
  306. #include <ewl_scrollbar.h>
  307. #include <ewl_spacer.h>
  308. #include <ewl_spinner.h>
  309. #include <ewl_image.h>
  310. #include <ewl_spectrum.h>
  311. #include <ewl_menu_item.h>
  312. #include <ewl_menu_base.h>
  313. #include <ewl_imenu.h>
  314. #include <ewl_menu.h>
  315. #include <ewl_menubar.h>
  316. #include <ewl_combo.h>
  317. #include <ewl_check.h>
  318. #include <ewl_checkbutton.h>
  319. #include <ewl_radiobutton.h>
  320. #include <ewl_separator.h>
  321. #include <ewl_calendar.h>
  322. #include <ewl_datepicker.h>
  323. #include <ewl_icon.h>
  324. #include <ewl_iconbox.h>
  325.  
  326. #include <ewl_notebook.h>
  327. #include <ewl_progressbar.h>
  328. #include <ewl_paned.h>
  329. #include <ewl_scrollpane.h>
  330. #include <ewl_statusbar.h>
  331. #include <ewl_dnd.h>
  332.  
  333. #include <ewl_tree.h>
  334.  
  335. #ifdef __cplusplus
  336. }
  337. #endif
  338. #endif
  339.